Andys Binary Folding Editor

The initialisation file

One of the first thing BE does is to find and load the initialisation file, and this tells BE the layout of various file formats and the structures within them.

Under OS/2 or Windows, BE finds the initialisation file by searching along the path for an .INI file with the same name. Under UNIX, BE looks for ~/.berc, (or ~/.xxrc if the be executable is renamed to xx). BE can be made to look elsewhere using the -i command line option.

This initialisation file may contain C or C++ style comments.

Also, $define, $ifdef, $ifndef, $else, $endif and $error are supported, as a form of a pre-processing/conditional processing step. The -D command line option may be used to pre-$define such conditional processing symbols.

If BE is running on OS/2, then OS2 is pre-$defined. If running on Windows NT or Windows 95, then WIN32 is pre-$defined. If running on a type of UNIX, then UNIX is pre-$defined. If running specifically on AIX, then AIX is pre-$defined. Either BE or LE will be pre-$defined, depending upon whether BE is running on a big-endian or little-endian machine. These $defines allow you to write initialisation files with sensible defaults, relevant for the current environment.

When the program starts parsing the initialisation file, the default data display attributes are le unsigned hex nomul abs nonull nocode nolj noseg.

To change this default setting, just include one or more of the following keywords in the file :-

• be - read multibyte values from memory in a big-endian fashion.
• le - read multibyte values from memory in a little-endian fashion.
• signed - when fetching numeric values sign extend them, and when displaying numerically show '+signedvalue' or '-signedvalue'.
• unsigned - when fetching numeric values zero extend them, and when displaying numerically show 'unsignedvalue'.
• asc - set display mode to ASCII.
• ebc - set display mode to EBCDIC.
• bin - set display mode to binary.
• oct - set display mode to octal.
• dec - set display mode to decimal.
• hex - set display mode to hex.
• sym - set display mode to symbolic. ie: look up the value in the symbol table, and if found, display symbol+hexoffset, else display value in hex.
• null - allow following of 0 pointers.
• nonull - disallow following of 0 pointers.
• seg - cope with 16:16 segmented pointers.
• noseg - pointers are not segmented.
• mul - pointer values should be multiplied by the size of the data type being pointed to.
• nomul - pointer values are given in regular byte addresses.
• abs - pointer values are absolute.
• rel - pointer values are to be considered relative to their own addresses.
• code - specify that numeric value is actually a code address.
• nocode - specify that numeric value is not a code address.
• lj - perform ARM specific long-jump interpretation of code addresses.
• nolj - don't do long-jump interpretation.

Map definitions

These define a mapping between symbolic names and numeric values. A typical mapping definition in the initialisation file might be :-

  map compression_type
    {
    "uncompressed" 1
    "huffman"      2
    "lzw"          3
    }

If the numeric value on display matches the value given, then it can be converted to the textual description.

Bitfields may be acheived in the following fashion :-

  map pending_events
    {
    "reconfiguration" 0x0001 : 0x0001
    "flush_cache"     0x0002 : 0x0002
    "restart_io"      0x0004 : 0x0004
    }

The : symbol introduces an additional mask. The number to string conversion algorithm inside BE works like this :-

  for each maplet in the map
    if ( value & maplet.mask ) == maplet.value then
      display the maplet.name
  if some unexplained bits left over then
      display the remaining value in hex

So, it is possible to have multiple field decodes from a single value :-

  map twobitfields
    {
    "green" 0x0001 : 0x000f
    "blue"  0x0002 : 0x000f
    "red"   0x0003 : 0x000f
    "small" 0x0100 : 0x0f00
    "large" 0x0200 : 0x0f00
    }

Structures are a list of at OFFSET clauses and field definitions. When the structure definition is processed, then the current-offset is initialised to 0.

An at OFFSET clause moves the current-offset to the specified numeric value.

  n8 asc "initial"
  n8 buf 20 "surname"
  n16 be unsigned dec "age"
  3 pet "pet names"
  3 n16 be unsigned dec "pet costs"
  2 n32 le unsigned hex ptr person "2 pointers to parents"
  2 n32 ptr person null "2 pointers, null legal"
  person "a person"
  n32 sym code "__main"
  1024 n32 unsigned dec "memory as 32 bit words"
  9 n16 map errorcodes "results"

Each example is of the form :-

  opt-count type opt-attrs name

The field describes count data items of the specified type, count is restricted to being >= 1, and if it is > 1, then the field is initially displayed by just showing its type (eg: 10 n32 le unsigned hex "numbers"). When you select the field, you are presented with an element list, with count lines, from which you can select the element you are interested in.

The type of the data is one of n8, n16, n24, n32, buf N or DEFN, where DEFN is the name of a previously defined structure. This type may be considered to be the way in which BE is told the size of the data item concerned. n8, n16, n24 and n32 mean 8, 16, 24 or 32 bit numeric data item. buf N means a buffer of N bytes.

The initialisation file can contain the following, as long as it is outside of any other definition :-

  include "anotherfile.ini"

A sample initialisation file

Here is a snippet from a real initialisation file :-

le unsigned hex abs // set defaults, just to be sure
lj // allow ARM specific symbolic lookup of code addresses

map DE_
  {
  "DP_Pending" -1
  "DS_Success"  0
  "DE_Failure"  1
  }

def DPB
  {
  n32 ptr DPB       "DPB_Next   "
  n32 sym code      "DPB_Address"
  n8 map DC_        "DPB_Number "
  n8                "DPB_Flag2  "
  n8 map SY_        "DPB_Flag   "
  n8 signed map DE_ "DPB_Dsb    "
  n32               "DPB_Safety "
  }

def NOP
  {
  DPB     "NOP_Header"
  n8      "NOP_Spare1"
  n8      "NOP_Spare2"
  n8      "NOP_Spare3"
  n8 dec  "NOP_Period"
  n32 dec "NOP_Value "
  CLK     "NOP_Clock "
  }

def main // the entire memory map
  {
  at addr "noptable"   100 NOP     "noptable  "
  at addr "currentdpb" n32 ptr DPB "currentdpb"
  }

The supplied initialisation file

The supplied initialisation file contains enough definitions to enable you to examine the contents of many image file formats.

These include Windows / OS/2 Bitmaps, Targa files, KIPS files, ZSoft PCX, M-Motion Video, TIFF, ILBM IFF, Compu$erve GIF, RiscOS sprite, IBM PSEG, and OS/2 resource files.

The definitions in the initialisation file are in no way complete, or intended to be a definitive statement of such files contents, but are merely intended to aid in the browsing of the contents of such files.

Limitations of BE make it awkward to decode certain data structures in some files, so the attitude taken is typically 'display as best you can', and where data may be of variable length 'display the first few bytes worth...'.

Using the editor

Although not displayed, the arrow keys, such as Up, Down, PgUp, PgDn, Home and End all work in the obvious ways, traversing the list on display. The Wordstar keys ^E, ^X, ^R, ^C, ^W and ^Z also work.

BE displays the non-obvious keys you may press on the 2nd line of its status area, at the top of the screen.

@X (ie: Alt+X), or q exits the program.

Esc exits the current screen back to the previous level.

f allows you to do a find over the list on display. This only searches as much as the user could see if he were to manually page up and down through the list. The find command is case sensitive. n can be used to repeat the last find.

i allows you to generate a display which only has lines which include a pattern you specify. For example, if you have an array of trace-point events, you can easily generate a list of just trace-points from one module. Similarly, x allows you generate a display which excludes lines which match the pattern. Esc exits back to the original display.

The keys A,O,I toggle the display of addresses, offsets and array indices.

The binary file arguments to BE are normally of the form :-

  filename[@address]

This tells BE to load the file and whenever data at a memory address from address to address+filelength is accessed, to supply the data from the file.

However, it is possible to supply binary file arguments of the form :-

  extension!args[@address]

Under OS/2, BE will ensure that BEextension.DLL is loaded. This DLL should be on the LIBPATH and should contain certain entrypoints which will be used by BE. BE then passes the args and address to the extension DLL, who does something of its own chosing with them. The extension DLL can then supply data to BE on request.

Under Windows, provision for extension DLLs is also exists. The DLL is located according to the algorithm used by the Win32 LoadLibrary API.

One use of this might be the provision of an extension for handling files too massive to load into memory all at once. The extension could open a file handle and read bytes demanded by BE upon request. This extension could be provided in BEBIGFIL.DLL, and the user could type :-

  be bigfil!verybigfile.dat

Another use might be in live-debug of adapter cards. The extension would provide data bytes from the memory space of the adapter. args could be used to identify the slot the adapter is in.

Yet another use, might be providing BE with access to physical or virtual or process specific linear address spaces, perhaps via the use of a device driver. Shared memory windows might give addressibility of datastructures in other programs.

Also, the surface of a disk or block device could be made accessible via an extension.

Perhaps bytes sent down a communications port could be made to appear as a stream of binary data.

The file bememext.h documents the extension interface. Currently extensions may only be built for the OS/2 or version of BE using the IBM C-Set++ compiler, or the Win32 version of BE using MS Visual C++. I anticipate learning about shared library support on the various different types of UNIX, enabling similar tricks to be performed there.

Installation

Installing BE for OS/2

1. Copy be_os2.exe to be.exe, somewhere on the path.
2. Copy be.ini to the same directory as be.exe so it can be found.
3. Optionally copy be.htm to wherever you keep documentation.
4. Optionally copy be.ico to the same directory as be.exe. This allows BE to have a cute icon when running in the Workplace shell.
5. Optionally create a Workplace Shell Program Object(s) that references the BE executable. The working directory should be the directory where be.ini can be found.

Installing BE for Windows NT or Windows 95

1. Copy be_win.exe to be.exe, somewhere on the path.
2. Copy be.ini to the same directory as be.exe so it can be found.
3. Optionally copy be.htm to wherever you keep documentation.

Installing AE for UNIX, ie: AIX

1. Copy the be executable to somewhere like /usr/bin or ~/bin, or wherever on the path you consider appropriate.
2. Copy the be.ini to .berc in your home directory, or make a soft link to a common .berc somewhere from your home directory.
3. Optionally copy be.htm to wherever you keep documentation.

Unfortunately I don't have continual access to all the platforms, so improvements in one version may not yet be reflected into the others.

Copying

Copying of this program is encouraged, as it is fully public domain. Caveat Emptor.